---
title: Docker Compose
description: Simple single-container deployment for small teams and basic self-hosting
---

# Docker Compose

Deploy Onlook using Docker Compose on VMs or local machines. This is a simple, single-container deployment designed for small teams and basic self-hosting needs. For enterprise-grade deployments requiring high availability and scalability, use the [Cloud Deployment](/self-hosting/cloud-deployment) option.

## Prerequisites

**System Requirements:**
- 4+ CPU cores
- 8GB+ RAM (16GB recommended)
- 50GB+ available disk space
- Docker 20.10+ and Docker Compose 2.0+

**Software Requirements:**
- [Bun](https://bun.sh) - Package manager and runtime
- [Node.js](https://nodejs.org/en/download) v20.16.0+ (avoid v20.11.0)
- [Git](https://git-scm.com/downloads)
- [Docker](https://docs.docker.com/get-docker/) & [Docker Compose](https://docs.docker.com/compose/install/)

## Basic Deployment

> **Note**: This is a simple deployment suitable for small teams and testing. For development, use `bun dev` in the repository root.

### 1. Clone the Repository

```bash
git clone https://github.com/onlook-dev/onlook.git
cd onlook

# Install dependencies
bun install
```

### 2. Setup Environment Variables

For Docker Compose deployment, you need to create a environment file.

```bash
# Run interactive environment setup
bun run setup:env
```

**Required variables:**
- **Supabase**: Production database URL and API keys
- **OpenRouter API Key**: For AI chat features  
- **CodeSandbox Token**: For development containers

For detailed instructions on obtaining these API keys, see the [development setup guide](/developers/running-locally#3-get-api-keys).

### 3. Start Backend Services

```bash
bun backend:start
```

This starts Supabase locally with PostgreSQL database, authentication, and storage. This will spin up a separate Docker compose service. For production supabase connection, change the Supabase API keys in the `.env` file.

### 4. Initialize Database

```bash
# Push database schema
bun db:push
```

### 5. Deploy with Docker Compose

Deploy the production container from the repository root:

```bash
docker-compose up -d
```

This builds and starts:
- **Web Application**: Production-built Next.js application (port 3000)
- **Health checks**: Automatic container health monitoring
- **Auto-restart**: Container restarts automatically on failure

**Note**: The Docker container uses `network_mode: "host"` to access the local Supabase services running on your host machine. This allows the container to connect to `http://127.0.0.1:54321` (Supabase API) and `127.0.0.1:54322` (PostgreSQL).

### 6. Verify Deployment

- **Main Application**: http://localhost:3000
- **Supabase Dashboard**: http://localhost:54323 (from backend:start)

Check the service is running:
```bash
docker-compose ps
curl http://localhost:3000
```

## Troubleshooting

**Common issues:**
- **Port 3000 in use**: Stop other services or change port  
- **Docker build fails**: Run `docker system prune` and retry
- **Database connection**: Verify `bun backend:start` is running and Supabase is accessible at http://127.0.0.1:54321
- **Container can't connect to Supabase**: Ensure `network_mode: "host"` is set in docker-compose.yml for localhost access

## Limitations & Considerations

**This deployment is designed for simplicity, not high reliability:**

**Limitations:**
- Single container (single point of failure)
- No built-in load balancing or auto-scaling  
- Manual backup and disaster recovery
- Limited to vertical scaling only
- No high availability guarantees

**Suitable for:**
- Small teams (< 10 users)
- Development/testing environments
- Proof of concept deployments
- Basic self-hosting needs

**Not suitable for:**
- Mission-critical production workloads
- Large teams requiring high availability
- Environments needing 99.9%+ uptime

For enterprise-grade deployments, use the [Cloud Deployment](/self-hosting/cloud-deployment) option with proper redundancy and scaling.